The Date Picker§

The basic setup requires targetting an input element and invoking the picker:

$('.datepicker').pickadate()

Options§

With the basic invocation above, these are the default settings:

// Strings and translations
monthsFull: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
monthsShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
weekdaysFull: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
weekdaysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
showMonthsShort: undefined,
showWeekdaysFull: undefined,

// Buttons
today: 'Today',
clear: 'Clear',
close: 'Close',

// Accessibility labels
labelMonthNext: 'Next month',
labelMonthPrev: 'Previous month',
labelMonthSelect: 'Select a month',
labelYearSelect: 'Select a year',

// Formats
format: 'd mmmm, yyyy',
formatSubmit: undefined,
hiddenPrefix: undefined,
hiddenSuffix: '_submit',
hiddenName: undefined,

// Editable input
editable: undefined,

// Dropdown selectors
selectYears: undefined,
selectMonths: undefined,

// First day of the week
firstDay: undefined,

// Date limits
min: undefined,
max: undefined,

// Disable dates
disable: undefined,

// Root picker container
container: undefined,

// Hidden input container
containerHidden: undefined,

// Close on a user action
closeOnSelect: true,
closeOnClear: true,

// Events
onStart: undefined,
onRender: undefined,
onOpen: undefined,
onClose: undefined,
onSet: undefined,
onStop: undefined,

// Classes
klass: {

  // The element states
  input: 'picker__input',
  active: 'picker__input--active',

  // The root picker and states *
  picker: 'picker',
  opened: 'picker--opened',
  focused: 'picker--focused',

  // The picker holder
  holder: 'picker__holder',

  // The picker frame, wrapper, and box
  frame: 'picker__frame',
  wrap: 'picker__wrap',
  box: 'picker__box',

  // The picker header
  header: 'picker__header',

  // Month navigation
  navPrev: 'picker__nav--prev',
  navNext: 'picker__nav--next',
  navDisabled: 'picker__nav--disabled',

  // Month & year labels
  month: 'picker__month',
  year: 'picker__year',

  // Month & year dropdowns
  selectMonth: 'picker__select--month',
  selectYear: 'picker__select--year',

  // Table of dates
  table: 'picker__table',

  // Weekday labels
  weekdays: 'picker__weekday',

  // Day states
  day: 'picker__day',
  disabled: 'picker__day--disabled',
  selected: 'picker__day--selected',
  highlighted: 'picker__day--highlighted',
  now: 'picker__day--today',
  infocus: 'picker__day--infocus',
  outfocus: 'picker__day--outfocus',

  // The picker footer
  footer: 'picker__footer',

  // Today, clear, & close buttons
  buttonClear: 'picker__button--clear',
  buttonClose: 'picker__button--close',
  buttonToday: 'picker__button--today'
}

Strings§

Change the month and weekday labels as you find suitable:

$('.datepicker').pickadate({
  weekdaysShort: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
  showMonthsShort: true
})

Buttons§

Change the text or hide a button completely by passing a false-y value:

$('.datepicker').pickadate({
  today: '',
  clear: 'Clear selection',
  close: 'Cancel'
})

Accessibility labels§

Change the title attributes to several elements within the picker:

$('.datepicker').pickadate({
  labelMonthNext: 'Go to the next month',
  labelMonthPrev: 'Go to the previous month',
  labelMonthSelect: 'Pick a month from the dropdown',
  labelYearSelect: 'Pick a year from the dropdown',
  selectMonths: true,
  selectYears: true
})

Translations§

The picker can be extended to add support for internationalization. Translations for over 40 languages are available out of the box, which you can include in one of two ways:

// Extend the default picker options for all instances.
$.extend($.fn.pickadate.defaults, {
  monthsFull: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
  weekdaysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
  today: 'aujourd\'hui',
  clear: 'effacer',
  formatSubmit: 'yyyy/mm/dd'
})

// Or, pass the months and weekdays as an array for each invocation.
$('.datepicker').pickadate({
  monthsFull: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
  weekdaysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
  today: 'aujourd\'hui',
  clear: 'effacer',
  formatSubmit: 'yyyy/mm/dd'
})

RTL languages§

For languages that flow from right-to-left (RTL), you’ll need to switch the arrows and text direction by linking along the rtl.css file:

<!-- Add the stylings *after* the pickadate theme files -->
<link rel="stylesheet" href="lib/themes/rtl.css">

<!-- Add the language *after* the pickadate script files -->
<script src="lib/translations/ar.js"></script>

Formats§

Display a human-friendly format and use an alternate one to submit to the server.

This is done by creating a new hidden input element with the same name attribute as the original with an optional prefix/suffix:

$('.datepicker').pickadate({
  // Escape any “rule” characters with an exclamation mark (!).
  format: 'You selecte!d: dddd, dd mmm, yyyy',
  formatSubmit: 'yyyy/mm/dd',
  hiddenPrefix: 'prefix__',
  hiddenSuffix: '__suffix'
})

Send the hidden value only§

A majority of the time, the value that needs to be sent to the server is just the hidden value – and not the visible one. To make this happen, use the hiddenName option.

This essentially nullifies the hiddenPrefix and hiddenSuffix, strips the name attribute from the source input, and then sets it as the name of the hidden input:

$('.datepicker').pickadate({
  formatSubmit: 'yyyy/mm/dd',
  hiddenName: true
})

Pre-fill values using custom formats or translations§

When using a custom formatting rule for the format option or when using translations, the input element should be given a data-value attribute formatted using the formatSubmit – the element’s value can be left blank. This helps to parse the date from custom formats into various languages:

<input data-value="2015/04/20">

Formatting Rules§

The following rules can be used to format any date:

Rule	Description	Result
d	Date of the month	1 – 31
dd	Date of the month with a leading zero	01 – 31
ddd	Day of the week in short form	Sun – Sat
dddd	Day of the week in full form	Sunday – Saturday
m	Month of the year	1 – 12
mm	Month of the year with a leading zero	01 – 12
mmm	Month name in short form	Jan – Dec
mmmm	Month name in full form	January – December
yy	Year in short form *	00 – 99
yyyy	Year in full form	2000 – 2999

Editable input§

By default, typing into the input is disabled by giving it a readOnly attribute. Doing so ensures that virtual keyboards don’t pop open on touch devices. It is also a confirmation that values passed to the server will be of a consistent format.

However, this behavior can be changed using the editable option:

$('.datepicker').pickadate({
  editable: true
})

Using HTML5 attributes§

Because each input is readOnly by default, HTML5 attributes, such as required and pattern, do not get enforced.

To enable default browser behavior on these attributes, set the editable property to true.

Dropdown Selectors§

Display select menus to pick the month and year. Anything truth-y enables the selectors and anything false-y switches them into text:

$('.datepicker').pickadate({
  selectYears: true,
  selectMonths: true
})

You can also specify the number of years to show in the dropdown using an even integer - half before and half after the year in focus:

$('.datepicker').pickadate({
  // `true` defaults to 10.
  selectYears: 4
})

First Weekday§

The first day of the week can be set to either Sunday or Monday. Anything truth-y sets it as Monday and anything false-y as Sunday:

$('.datepicker').pickadate({
  firstDay: 1
})

Date Limits§

Set the minimum and maximum selectable dates on the picker.

Using JavaScript dates§

$('.datepicker').pickadate({
  min: new Date(2015,3,20),
  max: new Date(2015,7,14)
})

Using arrays formatted as [YEAR,MONTH,DATE]§

$('.datepicker').pickadate({
  min: [2015,3,20],
  max: [2015,7,14]
})

Using integers or a boolean§

$('.datepicker').pickadate({
  // An integer (positive/negative) sets it relative to today.
  min: -15,
  // `true` sets it to today. `false` removes any limits.
  max: true
})

Disable Dates§

Disable a specific or arbitrary set of dates selectable on the picker.

Using JavaScript dates§

$('.datepicker').pickadate({
  disable: [
    new Date(2015,3,13),
    new Date(2015,3,29)
  ]
})

Using arrays formatted as [YEAR,MONTH,DATE]§

$('.datepicker').pickadate({
  disable: [
    [2015,3,3],
    [2015,3,12],
    [2015,3,20]
  ]
})

Using integers as days of the week (1 to 7)§

$('.datepicker').pickadate({
  disable: [
    1, 4, 7
  ]
})

Using objects as a range of dates§

$('.datepicker').pickadate({
  disable: [
    { from: [2016,2,14], to: [2016,2,27] }
  ]
})

The values for from & to can be:

• A JavaScript Date object,
• An array formatted as [YEAR,MONTH,DATE],
• And true to set it as “today”.

The values can also be integers representing dates relative to the other:

• to can only be positive:

  { from: [2016,3,12], to: 10 }

• from can only be negative:

  { from: -10, to: true }

Disabling all with a set of exceptions§

Enable only a specific or arbitrary set of dates by setting true as the first item in the collection:

$('.datepicker').pickadate({
  disable: [
    true,
    1, 4, 7,
    [2015,3,3],
    [2015,3,12],
    [2015,3,20],
    new Date(2015,3,13),
    new Date(2015,3,29)
  ]
})

Disabling ranges with exceptions§

Enable dates that fall within a range of disabled dates by adding the inverted parameter to the item within the collection:

$('.datepicker').pickadate({
  disable: [
    5,
    [2015, 10, 21, 'inverted'],
    { from: [2016, 3, 15], to: [2016, 3, 25] },
    [2016, 3, 20, 'inverted'],
    { from: [2016, 3, 17], to: [2016, 3, 18], inverted: true }
  ]
})

container§

By default, the picker’s root element is inserted right after the main input element. Specify where to insert the root element by passing any valid CSS selector or jQuery object to this option:

$('.datepicker').pickadate({
  container: '#root-picker-outlet'
})

container for the hidden input§

By default, the picker’s hidden input is inserted right after the main input element. Specify where to insert the hidden element by passing any valid CSS selector to this option:

$('.datepicker').pickadate({
  containerHidden: '#hidden-input-outlet'
})

Close on a user action §

When a date is selected or the “clear” button is pressed, the picker closes. To change this behavior, use the following options:

$('.datepicker').pickadate({
  closeOnSelect: false,
  closeOnClear: false
})

events§

Fire off events as the user interacts with the picker:

$('.datepicker').pickadate({
  onStart: function() {
    console.log('Hello there :)')
  },
  onRender: function() {
    console.log('Whoa.. rendered anew')
  },
  onOpen: function() {
    console.log('Opened up')
  },
  onClose: function() {
    console.log('Closed now')
  },
  onStop: function() {
    console.log('See ya.')
  },
  onSet: function(context) {
    console.log('Just set stuff:', context)
  }
})

The onSet event is the only callback that is passed a context argument that provides details as to which properties are being “set”.

Within scope of all six of these events, this refers to the picker.

To learn more on how to use the picker object, read the API documentation.